Ian Sommerville Lancaster University , UK

Introduction All large software development projects, irrespective of application, generate a large amount of associated documentation. For moderately sized systems, the documentation will probably fill several filing cabinets; for large systems, it may fill several rooms. A high proportion of software process costs is incurred in producing this documentation. Furthermore, documentation errors and omissions can lead to errors by end-users and consequent system failures with their associated costs and disruption. Therefore, managers and software engineers should pay as much attention to documentation and its associated costs as to the development of the software itself. The documents associated with a software project and the system being developed have a number of associated requirements: 1. They should act as a communication medium between members of the development team. 2. They should be a system information repository to be used by maintenance engineers. 3. They should provide information for management to help them plan, budget and schedule the software development process. 4. Some of the documents should tell users how to use and administer the system. Satisfying these requirements requires different types of document from informal working documents through to professionally produced user manuals. Software engineers are usually responsible for producing most of this documentation although professional technical writers may assist with the final polishing of externally released information. My goals here are to describe the documentation which may be produced during the software process, to give some hints on ways of writing effective documents and to describe processes involved in producing these documents. I start by discussing different types of documentation that may be produced in a software project. I then cover the important topic of document quality and discuss document structure, documentation standards and effective writing style. Finally, I cover processes of preparing, producing and managing documents. My focus in this paper is on documentation that is intended to be printed and so is delivered on paper or in a format such as PDF which may be viewed on a screen or locally printed. Many systems now also have associated hypertext help systems. Producing these systems requires a different set of skills from producing paper documentation and I only discuss these briefly here. For large software projects, it is usually the case that documentation starts being generated well before the development process begins. A proposal to develop the system may be produced in response to a request for tenders by an …